/**
 * Copyright (C) 2012 Foxit Corporation.
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation.<br> 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit.<br>
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement.<br>
 * Without SDK license agreement, you cannot redistribute anything.
 * 
 * @file	fpdfasync.h
 * @brief	Header file for the PDF async module.
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling PDF object module explicitly. 
 */
  
/** 
 * @addtogroup PDFASYNC PDF Async 
 * @brief Methods in this module are included in fpdfasync.h 
 */
/** @{*/
#ifndef __FGSPDFASYNC__
#define __FGSPDFASYNC__

#include "fpdfbase.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
* @brief An interface for receiving download hints. Use to receive hints for further downloading.
*/    
typedef struct  __FGSPDFAsyncDownloadHints
{
    /** @brief The size of the data structure. It must be set to sizeof<b>::FGSPDFAsyncDownloadHints</b>. */
    SInt32		size; 
    
    /** @brief The user-supplied data. */
    void *		clientData;
    
    /**
     * @brief Report whether the specified data section is available. A section is available only if all bytes in the section are available. 
     *
     * @param[in] clientData		The user-supplied data.
     * @param[in] offset			The offset of the SInt32 reported to be downloaded.
     * @param[in] size				The size of the SInt32 reported to be downloaded.
     *
     * @return ::kFGSErrorSuccess means importing successfully.<br>
     *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
     * @note Called by the Foxit SDK to check whether the data section is ready.
     */
    Boolean (*isDataAvail)(void *clientData, SInt32 offset, SInt32 size);
    
	/**
	 * @brief Add a section to be downloaded.
     *
	 * @param[out] pThis		Pointer to the interface structure itself.
	 * @param[in] offset		The offset of the hints reported to be downloaded.
	 * @param[in] size			The size of the hints reported to be downloaded.
	 * @note Called by the Foxit SDK to report downloading hints for the download manager.
	 *		 The position and size of the section may not be accurate because part of the section might 
	 *       already be available. The download manager must manage this to maximize download efficiency.
	 * @return None.
	 */
   void (*addSegment)(void *clientData, SInt32 offset, SInt32 size);
    
} FGSPDFAsyncDownloadHints;

/**
 * @brief Create a document availability provider.
 *
 * @param[in] file_avail		Pointer to the file availability interface to check availability of file data.
 * @param[in] file				Pointer to a file access interface for reading data from file.
 * @param[out] avail			Reference to the document availability provider or NULL to indicate an error occurred.
 *
 * @return ::kFGSErrorSuccess means importing successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 * @note   Application must call <b>::FGSPDFAsyncDestroy</b> when done with the availability provider.
 */
FGSErrorRet FGSPDFAsyncCreate(FGSPDFAsyncDownloadHints *file_avail, CFStringRef file, FGSPDFAsyncRef *avail);
    
/**
 * @brief Destroy a document availability provider. 
 *
 * @param[in] avail				Reference to the document availability provider returned by <b>::FGSPDFAsyncCreate</b>.
 *
 * @return None
 */
void FGSPDFAsyncDestroy(FGSPDFAsyncRef avail);

/**
 * @brief Check whether the document is ready for loading, if not, get download hints.
 *
 * @param[in] avail				Reference to the document availability provider returned by <b>::FGSPDFAsyncCreate</b>.
 * @param[in] hints				Pointer to a download hints structure that will receive generated hints.
 * @param[out] isAvail			Whether the page is full available.
 *
 * @return Whether the page is full available.
 *
 * @note	The application should call this function whenever new data arrives.  It should process all the
 *			generated download hints, if any, until the function returns a non-zero value. Then the 
 *			application can call <b>::FGSPDFAsyncGetDocument</b> to get a document reference.
 */
Boolean FGSPDFAsyncIsDocAvail(FGSPDFAsyncRef avail);
    
/**
 * @brief Get document from the availability provider.
 *
 * @param[in] avail				Reference to the document availability provider returned by FGSPDFAsyncCreate.
 * @param[out] doc				Reference to the document or NULL if an error occurs.
 *
 * @return ::kFGSErrorSuccess means importing successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 * @note After <b>::FGSPDFAsyncIsDocAvail</b> returns TRUE, the application should call this function to
 *		get the document handle. To close the document, use the <b>::FGSPDFDocCloseDoc</b> function.
 */
FGSErrorRet FGSPDFAsyncGetDocument(FGSPDFAsyncRef avail, FGSPDFDocumentRef *doc);
    
/**
 * @brief Get the page number of the first available page in a linearized PDF.
 *
 * @param[in] document			Reference to the document which is returned by <b>::FGSPDFAsyncGetDocument</b>.
 *	
 * @return Zero-based index for the first available page.
 *	
 * @note For most linearized PDFs, the first available page would be just the first page. However,
 *		there are some PDFs that set the first available page to be a page other than the first page.
 *		For non-linearized PDF, this function will always return zero.
 */
SInt32 FGSPDFAsyncGetFirstPageNum(FGSPDFDocumentRef document);
	
/**
 * @brief Check whether a page is ready for loading, if not, get download hints.
 *
 * @param[in] avail				Reference to the document availability provider returned by <b>::FGSPDFAsyncCreate</b>.
 * @param[in] page_index		Index number of the page. 0 for the first page.
 * @param[out] hints			Pointer to a download hints interface structure that receives generated hints.
 *
 * @return Whether the page is available.
 *
 * @note This function can only be called after <b>::FGSPDFAsyncGetDocument</b> is called.
 *		The application should call this function whenever new data arrives. It should process all the
 *		generated download hints, if any, until the function returns a non-zero value. Then the 
 *		application can perform page loading.
 */
Boolean FGSPDFAsyncIsPageAvail(FGSPDFAsyncRef avail, SInt32 page_index);

/**
 * @brief Check whether form data is ready for initialization, if not, get download hints.
 *
 * @param[in] avail				Reference to the document availability provider returned by <b>::FGSPDFAsyncCreate</b>.
 * @param[out] hints			Pointer to a download hints interface structure that receives generated hints.
 *
 * @return Non-zero value indicates form data is fully available, 0 indicates form data is not yet available.
 *								Details: 
 *								<ul>
  *								<li> -1:  Error, the input parameter is not correct (e.g. hints is NULL).</li>
 *								<li> 0 :  Data is not available.</li>
 *								<li> 1 :  Data is available.</li>
 *								<li> 2 :  No form data.</li>
 *								</ul>
 *
 * @note This function can only be called after FPDF_Async_GetDocument is called. 
 *		The application should call this function whenever new data arrives. The application should process all the
 *		generated download hints, if any, until the function returns a non-zero value. Then the 
 *		application can perform page loading.
 */
Boolean FGSPDFAsyncIsFormAvail(FGSPDFAsyncRef avail);

/**
 * @brief Check whether a document is a Linearized PDF.
 *
 * @param[in] avail				Reference to the document availability provider returned by FPDF_Async_Create.
 *
 * @return Returns TRUE or FALSE as soon as the first 1K chunk of data is received. 
 */
Boolean FGSPDFAsyncIsLinearized(FGSPDFAsyncRef avail);

#ifdef __cplusplus
};
#endif

#endif // __FGSPDFASYNC__
/**@}*/


